home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 July: Mac OS SDK / Dev.CD Jul 00 SDK2.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / QD3DView.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  15.2 KB  |  476 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        QD3DView.h
  3.  
  4.      Contains:    View types and routines                                            
  5.  
  6.      Version:    Technology:    Quickdraw 3D 1.6
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c) 1995-1999 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __QD3DVIEW__
  18. #define __QD3DVIEW__
  19.  
  20. #ifndef __QD3D__
  21.     #include <QD3D.h>
  22. #endif
  23.  
  24.  
  25. #ifndef __QD3DSTYLE__
  26.     #include <QD3DStyle.h>
  27. #endif
  28.  
  29. #ifndef __QD3DSET__
  30.     #include <QD3DSet.h>
  31. #endif
  32.  
  33.  
  34.  
  35.  
  36. #if PRAGMA_ONCE
  37. #pragma once
  38. #endif
  39.  
  40. #ifdef __cplusplus
  41. extern "C" {
  42. #endif
  43.  
  44. #if PRAGMA_IMPORT
  45. #pragma import on
  46. #endif
  47.  
  48. #if PRAGMA_STRUCT_ALIGN
  49.     #pragma options align=power
  50. #elif PRAGMA_STRUCT_PACKPUSH
  51.     #pragma pack(push, 2)
  52. #elif PRAGMA_STRUCT_PACK
  53.     #pragma pack(2)
  54. #endif
  55.  
  56. #if PRAGMA_ENUM_ALWAYSINT
  57.     #pragma enumsalwaysint on
  58. #elif PRAGMA_ENUM_OPTIONS
  59.     #pragma option enum=int
  60. #elif PRAGMA_ENUM_PACK
  61.     #if __option(pack_enums)
  62.         #define PRAGMA_ENUM_PACK__QD3DVIEW__
  63.     #endif
  64.     #pragma options(!pack_enums)
  65. #endif
  66.  
  67. /******************************************************************************
  68.  **                                                                             **
  69.  **                        View Type Definitions                                 **
  70.  **                                                                             **
  71.  *****************************************************************************/
  72.  
  73. enum TQ3ViewStatus {
  74.     kQ3ViewStatusDone            = 0,
  75.     kQ3ViewStatusRetraverse        = 1,
  76.     kQ3ViewStatusError            = 2,
  77.     kQ3ViewStatusCancelled        = 3
  78. };
  79. typedef enum TQ3ViewStatus TQ3ViewStatus;
  80.  
  81.  
  82. /******************************************************************************
  83.  **                                                                             **
  84.  **                        Default Attribute Set                                 **
  85.  **                                                                             **
  86.  *****************************************************************************/
  87. #define kQ3ViewDefaultAmbientCoefficient    1.0
  88. #define kQ3ViewDefaultDiffuseColor            1.0, 1.0, 1.0
  89. #define kQ3ViewDefaultSpecularColor            0.5, 0.5, 0.5
  90. #define kQ3ViewDefaultSpecularControl        4.0
  91. #define kQ3ViewDefaultTransparency            1.0, 1.0, 1.0
  92. #define kQ3ViewDefaultHighlightState        kQ3Off
  93. #define kQ3ViewDefaultHighlightColor        1.0, 0.0, 0.0
  94. #define kQ3ViewDefaultSubdivisionMethod        kQ3SubdivisionMethodScreenSpace
  95. #define kQ3ViewDefaultSubdivisionC1            20.0
  96. #define kQ3ViewDefaultSubdivisionC2            20.0
  97.  
  98. /******************************************************************************
  99.  **                                                                             **
  100.  **                            View Routines                                     **
  101.  **                                                                             **
  102.  *****************************************************************************/
  103. EXTERN_API_C( TQ3ViewObject )
  104. Q3View_New                        (void);
  105.  
  106. EXTERN_API_C( TQ3Status )
  107. Q3View_Cancel                    (TQ3ViewObject             view);
  108.  
  109. /******************************************************************************
  110.  **                                                                             **
  111.  **                        View Rendering routines                                 **
  112.  **                                                                             **
  113.  *****************************************************************************/
  114. EXTERN_API_C( TQ3Status )
  115. Q3View_SetRendererByType        (TQ3ViewObject             view,
  116.                                  TQ3ObjectType             theType);
  117.  
  118. EXTERN_API_C( TQ3Status )
  119. Q3View_SetRenderer                (TQ3ViewObject             view,
  120.                                  TQ3RendererObject         renderer);
  121.  
  122. EXTERN_API_C( TQ3Status )
  123. Q3View_GetRenderer                (TQ3ViewObject             view,
  124.                                  TQ3RendererObject *    renderer);
  125.  
  126. EXTERN_API_C( TQ3Status )
  127. Q3View_StartRendering            (TQ3ViewObject             view);
  128.  
  129. EXTERN_API_C( TQ3ViewStatus )
  130. Q3View_EndRendering                (TQ3ViewObject             view);
  131.  
  132. EXTERN_API_C( TQ3Status )
  133. Q3View_Flush                    (TQ3ViewObject             view);
  134.  
  135. EXTERN_API_C( TQ3Status )
  136. Q3View_Sync                        (TQ3ViewObject             view);
  137.  
  138.  
  139. /******************************************************************************
  140.  **                                                                             **
  141.  **                        View/Bounds/Pick routines                             **
  142.  **                                                                             **
  143.  *****************************************************************************/
  144. EXTERN_API_C( TQ3Status )
  145. Q3View_StartBoundingBox            (TQ3ViewObject             view,
  146.                                  TQ3ComputeBounds         computeBounds);
  147.  
  148. EXTERN_API_C( TQ3ViewStatus )
  149. Q3View_EndBoundingBox            (TQ3ViewObject             view,
  150.                                  TQ3BoundingBox *        result);
  151.  
  152. EXTERN_API_C( TQ3Status )
  153. Q3View_StartBoundingSphere        (TQ3ViewObject             view,
  154.                                  TQ3ComputeBounds         computeBounds);
  155.  
  156. EXTERN_API_C( TQ3ViewStatus )
  157. Q3View_EndBoundingSphere        (TQ3ViewObject             view,
  158.                                  TQ3BoundingSphere *    result);
  159.  
  160. EXTERN_API_C( TQ3Status )
  161. Q3View_StartPicking                (TQ3ViewObject             view,
  162.                                  TQ3PickObject             pick);
  163.  
  164. EXTERN_API_C( TQ3ViewStatus )
  165. Q3View_EndPicking                (TQ3ViewObject             view);
  166.  
  167.  
  168. /******************************************************************************
  169.  **                                                                             **
  170.  **                            View/Camera routines                             **
  171.  **                                                                             **
  172.  *****************************************************************************/
  173. EXTERN_API_C( TQ3Status )
  174. Q3View_GetCamera                (TQ3ViewObject             view,
  175.                                  TQ3CameraObject *        camera);
  176.  
  177. EXTERN_API_C( TQ3Status )
  178. Q3View_SetCamera                (TQ3ViewObject             view,
  179.                                  TQ3CameraObject         camera);
  180.  
  181.  
  182. /******************************************************************************
  183.  **                                                                             **
  184.  **                            View/Lights routines                             **
  185.  **                                                                             **
  186.  *****************************************************************************/
  187. EXTERN_API_C( TQ3Status )
  188. Q3View_SetLightGroup            (TQ3ViewObject             view,
  189.                                  TQ3GroupObject         lightGroup);
  190.  
  191. EXTERN_API_C( TQ3Status )
  192. Q3View_GetLightGroup            (TQ3ViewObject             view,
  193.                                  TQ3GroupObject *        lightGroup);
  194.  
  195.  
  196. /******************************************************************************
  197.  **                                                                             **
  198.  **                                Idle Method                                     **
  199.  **                                                                             **
  200.  *****************************************************************************/
  201. /*
  202.  *    The idle methods allow the application to register callback routines 
  203.  *    which will be called by the view during especially long operations.
  204.  *
  205.  *    The idle methods may also be used to interrupt long renderings or
  206.  *    traversals.  Inside    the idler callback the application can check for
  207.  *    Command-Period, Control-C or clicking a "Cancel" button or whatever else
  208.  *    may be used to let the user interrupt rendering.    
  209.  *
  210.  *    It is NOT LEGAL to call QD3D routines inside an idler callback.
  211.  *
  212.  *    Return kQ3Failure to cancel rendering, kQ3Success to continue. Don't
  213.  *    bother posting an error.
  214.  *
  215.  *    Q3View_SetIdleMethod registers a callback that can be called
  216.  *    by the system during rendering.  Unfortunately there is no way yet
  217.  *    to set timer intervals when you want to be called.  Basically, it is
  218.  *    up to the application's idler callback to check clocks to see if you
  219.  *    were called back only a millisecond ago or an hour ago!
  220.  *
  221.  *    Q3View_SetIdleProgressMethod registers a callback that also gives
  222.  *    progress information. This information is supplied by the renderer, and
  223.  *    may or may not be based on real time.
  224.  *
  225.  *    If a renderer doesn't support the progress method, your method will be
  226.  *    called with current == 0 and completed == 0.
  227.  *    
  228.  *    Otherwise, you are GUARANTEED to get called at least 2 or more times:
  229.  *    
  230.  *    ONCE            idleMethod(view, 0, n)        -> Initialize, Show Dialog
  231.  *    zero or more    idleMethod(view, 1..n-1, n) -> Update progress
  232.  *    ONCE            idleMethod(view, n, n)        -> Exit, Hide Dialog
  233.  *    
  234.  *    "current" is guaranteed to be less than or equal to "completed"
  235.  *    "completed" may change values, but current/complete always indicates
  236.  *    the degree of completion.
  237.  *
  238.  *    The calling conventions aid in managing any data associated with a 
  239.  *    progress user interface indicator.
  240.  */
  241. typedef CALLBACK_API_C( TQ3Status , TQ3ViewIdleMethod )(TQ3ViewObject view, const void *idlerData);
  242. typedef CALLBACK_API_C( TQ3Status , TQ3ViewIdleProgressMethod )(TQ3ViewObject view, const void *idlerData, unsigned long current, unsigned long completed);
  243. EXTERN_API_C( TQ3Status )
  244. Q3View_SetIdleMethod            (TQ3ViewObject             view,
  245.                                  TQ3ViewIdleMethod         idleMethod,
  246.                                  const void *            idleData);
  247.  
  248. EXTERN_API_C( TQ3Status )
  249. Q3View_SetIdleProgressMethod    (TQ3ViewObject             view,
  250.                                  TQ3ViewIdleProgressMethod  idleMethod,
  251.                                  const void *            idleData);
  252.  
  253.  
  254. /******************************************************************************
  255.  **                                                                             **
  256.  **                                EndFrame Method                                 **
  257.  **                                                                             **
  258.  *****************************************************************************/
  259. /*
  260.  *    The end frame method is an alternate way of determining when an
  261.  *    asynchronous renderer has completed rendering a frame. It differs from
  262.  *    Q3View_Sync in that notification of the frame completion is the opposite
  263.  *    direction. 
  264.  *    
  265.  *    With Q3View_Sync the application asks a renderer to finish rendering
  266.  *    a frame, and blocks until the frame is complete.
  267.  *    
  268.  *    With the EndFrame method, the renderer tells the application that is has
  269.  *    completed a frame.
  270.  *
  271.  *    If "Q3View_Sync" is called BEFORE this method has been called, this
  272.  *    method will NOT be called ever.
  273.  *    
  274.  *    If "Q3View_Sync" is called AFTER this method has been called, the
  275.  *    call will return immediately (as the frame has already been completed).
  276.  */
  277. typedef CALLBACK_API_C( void , TQ3ViewEndFrameMethod )(TQ3ViewObject view, void *endFrameData);
  278. EXTERN_API_C( TQ3Status )
  279. Q3View_SetEndFrameMethod        (TQ3ViewObject             view,
  280.                                  TQ3ViewEndFrameMethod     endFrame,
  281.                                  void *                    endFrameData);
  282.  
  283.  
  284. /******************************************************************************
  285.  **                                                                             **
  286.  **                            Push/Pop routines                                 **
  287.  **                                                                             **
  288.  *****************************************************************************/
  289. EXTERN_API_C( TQ3Status )
  290. Q3Push_Submit                    (TQ3ViewObject             view);
  291.  
  292. EXTERN_API_C( TQ3Status )
  293. Q3Pop_Submit                    (TQ3ViewObject             view);
  294.  
  295. EXTERN_API_C( TQ3StateOperatorObject )
  296. Q3Push_New                        (void);
  297.  
  298. EXTERN_API_C( TQ3StateOperatorObject )
  299. Q3Pop_New                        (void);
  300.  
  301. EXTERN_API_C( TQ3Status )
  302. Q3StateOperator_Submit            (TQ3StateOperatorObject  stateOperator,
  303.                                  TQ3ViewObject             view);
  304.  
  305.  
  306. /******************************************************************************
  307.  **                                                                             **
  308.  **        Check if bounding box is visible in the viewing frustum.  Transforms **
  309.  **        the bbox by the current local_to_world transformation matrix and     **
  310.  **        does a clip test to see if it lies in the viewing frustum.             **
  311.  **        This can be used by applications to cull out large chunks of scenes     **
  312.  **        that are not going to be visible.                                     **
  313.  **                                                                             **
  314.  **        The default implementation is to always return kQ3True.  Renderers     **
  315.  **        may override this routine however to do the checking.                 **
  316.  **                                                                             **
  317.  *****************************************************************************/
  318. EXTERN_API_C( TQ3Boolean )
  319. Q3View_IsBoundingBoxVisible        (TQ3ViewObject             view,
  320.                                  const TQ3BoundingBox *    bbox);
  321.  
  322.  
  323. /******************************************************************************
  324.  **                                                                             **
  325.  **        Allows display groups to be culled if they are assigned bounding     **
  326.  **        boxes.                                                                  **
  327.  **                                                                             **
  328.  *****************************************************************************/
  329. EXTERN_API_C( TQ3Status )
  330. Q3View_AllowAllGroupCulling        (TQ3ViewObject             view,
  331.                                  TQ3Boolean             allowCulling);
  332.  
  333.  
  334.  
  335. /******************************************************************************
  336.  **                                                                             **
  337.  **                            DrawContext routines                             **
  338.  **                                                                             **
  339.  *****************************************************************************/
  340. EXTERN_API_C( TQ3Status )
  341. Q3View_SetDrawContext            (TQ3ViewObject             view,
  342.                                  TQ3DrawContextObject     drawContext);
  343.  
  344. EXTERN_API_C( TQ3Status )
  345. Q3View_GetDrawContext            (TQ3ViewObject             view,
  346.                                  TQ3DrawContextObject *    drawContext);
  347.  
  348.  
  349. /******************************************************************************
  350.  **                                                                             **
  351.  **                            Graphics State routines                             **
  352.  **                                                                             **
  353.  ** The graphics state routines can only be called while rendering (ie. in     **
  354.  ** between calls to start and end rendering calls).  If they are called     **
  355.  ** outside of a rendering loop, they will return with error.                 **
  356.  **                                                                             **
  357.  *****************************************************************************/
  358. /******************************************************************************
  359.  **                                                                             **
  360.  **                            Transform routines                                 **
  361.  **                                                                             **
  362.  *****************************************************************************/
  363. EXTERN_API_C( TQ3Status )
  364. Q3View_GetLocalToWorldMatrixState (TQ3ViewObject         view,
  365.                                  TQ3Matrix4x4 *            matrix);
  366.  
  367. EXTERN_API_C( TQ3Status )
  368. Q3View_GetWorldToFrustumMatrixState (TQ3ViewObject         view,
  369.                                  TQ3Matrix4x4 *            matrix);
  370.  
  371. EXTERN_API_C( TQ3Status )
  372. Q3View_GetFrustumToWindowMatrixState (TQ3ViewObject     view,
  373.                                  TQ3Matrix4x4 *            matrix);
  374.  
  375.  
  376. /******************************************************************************
  377.  **                                                                             **
  378.  **                            Style state routines                             **
  379.  **                                                                             **
  380.  *****************************************************************************/
  381. EXTERN_API_C( TQ3Status )
  382. Q3View_GetBackfacingStyleState    (TQ3ViewObject             view,
  383.                                  TQ3BackfacingStyle *    backfacingStyle);
  384.  
  385. EXTERN_API_C( TQ3Status )
  386. Q3View_GetInterpolationStyleState (TQ3ViewObject         view,
  387.                                  TQ3InterpolationStyle * interpolationType);
  388.  
  389. EXTERN_API_C( TQ3Status )
  390. Q3View_GetFillStyleState        (TQ3ViewObject             view,
  391.                                  TQ3FillStyle *            fillStyle);
  392.  
  393. EXTERN_API_C( TQ3Status )
  394. Q3View_GetHighlightStyleState    (TQ3ViewObject             view,
  395.                                  TQ3AttributeSet *        highlightStyle);
  396.  
  397. EXTERN_API_C( TQ3Status )
  398. Q3View_GetSubdivisionStyleState    (TQ3ViewObject             view,
  399.                                  TQ3SubdivisionStyleData * subdivisionStyle);
  400.  
  401. EXTERN_API_C( TQ3Status )
  402. Q3View_GetOrientationStyleState    (TQ3ViewObject             view,
  403.                                  TQ3OrientationStyle *    fontFacingDirectionStyle);
  404.  
  405. EXTERN_API_C( TQ3Status )
  406. Q3View_GetReceiveShadowsStyleState (TQ3ViewObject         view,
  407.                                  TQ3Boolean *            receives);
  408.  
  409. EXTERN_API_C( TQ3Status )
  410. Q3View_GetPickIDStyleState        (TQ3ViewObject             view,
  411.                                  unsigned long *        pickIDStyle);
  412.  
  413. EXTERN_API_C( TQ3Status )
  414. Q3View_GetPickPartsStyleState    (TQ3ViewObject             view,
  415.                                  TQ3PickParts *            pickPartsStyle);
  416.  
  417. EXTERN_API_C( TQ3Status )
  418. Q3View_GetAntiAliasStyleState    (TQ3ViewObject             view,
  419.                                  TQ3AntiAliasStyleData * antiAliasData);
  420.  
  421.  
  422. /******************************************************************************
  423.  **                                                                             **
  424.  **                        Attribute state routines                             **
  425.  **                                                                             **
  426.  *****************************************************************************/
  427. EXTERN_API_C( TQ3Status )
  428. Q3View_GetDefaultAttributeSet    (TQ3ViewObject             view,
  429.                                  TQ3AttributeSet *        attributeSet);
  430.  
  431. EXTERN_API_C( TQ3Status )
  432. Q3View_SetDefaultAttributeSet    (TQ3ViewObject             view,
  433.                                  TQ3AttributeSet         attributeSet);
  434.  
  435.  
  436. EXTERN_API_C( TQ3Status )
  437. Q3View_GetAttributeSetState        (TQ3ViewObject             view,
  438.                                  TQ3AttributeSet *        attributeSet);
  439.  
  440. EXTERN_API_C( TQ3Status )
  441. Q3View_GetAttributeState        (TQ3ViewObject             view,
  442.                                  TQ3AttributeType         attributeType,
  443.                                  void *                    data);
  444.  
  445.  
  446.  
  447.  
  448. #if PRAGMA_ENUM_ALWAYSINT
  449.     #pragma enumsalwaysint reset
  450. #elif PRAGMA_ENUM_OPTIONS
  451.     #pragma option enum=reset
  452. #elif defined(PRAGMA_ENUM_PACK__QD3DVIEW__)
  453.     #pragma options(pack_enums)
  454. #endif
  455.  
  456. #if PRAGMA_STRUCT_ALIGN
  457.     #pragma options align=reset
  458. #elif PRAGMA_STRUCT_PACKPUSH
  459.     #pragma pack(pop)
  460. #elif PRAGMA_STRUCT_PACK
  461.     #pragma pack()
  462. #endif
  463.  
  464. #ifdef PRAGMA_IMPORT_OFF
  465. #pragma import off
  466. #elif PRAGMA_IMPORT
  467. #pragma import reset
  468. #endif
  469.  
  470. #ifdef __cplusplus
  471. }
  472. #endif
  473.  
  474. #endif /* __QD3DVIEW__ */
  475.  
  476.